Skip to main content

Reporting Service API Documentation

Overview​

This is a Spring Boot-based reporting service that handles immunization-related reports and data synchronization. The service reads data from a replica database and provides APIs for generating various immunization reports.

Base URL

text

/api/reports

Reporting Endpoints (ReportingResource.java)​

1. Yearly Enrollment Summary​

GET /summary-enrollment-yearly

Description: Get yearly enrollment summary report.

Query Parameters:

  • pId (optional): Program ID
  • locId (optional): Location ID
  • center (optional): Center name
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (optional): From date (dd-MM-yyyy)

Response: List<Map<String, Object>>

2. Gender-Based Enrollment Report​

GET /enrollment-by-gender

Description: Get enrollment statistics grouped by gender.

Query Parameters: Same as yearly enrollment summary

Response: List<Map<String, Object>>

3. Facts - Children FIC​

GET /facts-children-fic

Description: Get facts about children's Fully Immunized Coverage (FIC).

Query Parameters:

  • locationId (optional): Location ID
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)

Response: JSON String

4. Complete Facts Report​

GET /facts-full

Description: Get comprehensive facts report.

Query Parameters:

  • locationId (optional): Location ID
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)

Response: JSON String

5. Children Facts Report​

GET /facts-children

Description: Get facts specific to children.

Query Parameters: Same as facts-full

Response: JSON String

6. General Facts Report​

GET /facts

Description: Get general facts report.

Query Parameters: Same as facts-full

Response: JSON String

7. Targets Report​

GET /targets

Description: Get target data for locations.

Query Parameters:

  • locationId (required): Location ID
  • typeValue1 (optional): Filter for range from
  • typeValue2 (optional): Filter for range to
  • convertToMap (optional): Convert array to map with attributeName as keys

Response: JSON String (array or object based on convertToMap)

8. Coverage Report​

GET /CoverageReport

Description: Get vaccination coverage report.

Query Parameters:

  • location (required): Location
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)
  • vaccineId (required): Vaccine IDs (comma-separated)
  • locationType (required): Location type

Response: Map<String, Object>

9. Enrollment by Center​

GET /enrollmentByCenter

Description: Get enrollment statistics by center.

Query Parameters:

  • location (required): Location
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)
  • eventType (required): Event type

Response: Map<String, Object>

10. Enrollment by Vaccinator​

GET /enrollmentByVacc

Description: Get enrollment statistics by vaccinator.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

11. TT Enrollment by Center​

GET /ttEnrollByCenter

Description: Get Tetanus Toxoid enrollment by center.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

12. TT Enrollment by Vaccinator​

GET /ttEnrollByVaccinator

Description: Get Tetanus Toxoid enrollment by vaccinator.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

13. Age-Appropriate Coverage​

GET /ageAppropriate

Description: Get age-appropriate coverage statistics.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

14. Immunization by Vaccinator​

GET /immunizationByVacc

Description: Get immunization statistics by vaccinator.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

15. Immunization by Center​

GET /immunizationByCenter

Description: Get immunization statistics by center.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

16. Refusal by Vaccinator​

GET /refusalByVacc

Description: Get refusal statistics by vaccinator.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

17. Refusal by Center​

GET /refusalByCenter

Description: Get refusal statistics by center.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

18. TT Immunization by Vaccinator​

GET /TTImmunizationByVaccinator

Description: Get TT immunization statistics by vaccinator.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

19. Immunization Visit by Vaccinator​

GET /immunizationVisitByVaccinator

Description: Get immunization visit statistics by vaccinator.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

20. Immunization TT by Center​

GET /immunizationTTByCenter

Description: Get TT immunization statistics by center.

Query Parameters: Same as enrollmentByCenter

Response: Map<String, Object>

21. Daily Summary - Children Vaccination​

GET /daily-summary-vaccinations-children

Description: Get daily summary of children vaccinations.

Query Parameters:

  • locationId (required): Location ID
  • filterDatefrom (required): Date (dd-MM-yyyy)

Response: JSON String

22. Fully Immunized Coverage by Location​

GET /fic-by-location

Description: Get FIC statistics by location.

Query Parameters:

  • locationId (optional): Location ID
  • locType (optional): Location type
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)

Response: JSON String

23. Attendance Graphs by Day​

GET /attendance-graphs-by-day

Description: Get attendance statistics by day.

Query Parameters:

  • locationId (optional): Location ID
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)

Response: JSON String

24. Attendance Graphs by Week & Location​

GET /attendance-graphs-by-week-location

Description: Get weekly attendance statistics by location.

Query Parameters:

  • locationId (optional): Location ID
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)
  • locationType (optional): Location type

Response: List

25. Daily Summary - Full Vaccination​

GET /daily-summary-vaccinations-full

Description: Get daily summary of full vaccinations.

Query Parameters:

  • locationId (required): Location ID
  • filterDatefrom (required): Date (dd-MM-yyyy)

Response: JSON String

26. Daily Summary - Women Vaccination​

GET /daily-summary-vaccinations-women

Description: Get daily summary of women vaccinations.

Query Parameters: Same as daily summary full

Response: JSON String

27. Population-Based Coverage by District​

GET /population-based-coverage/{locId}

Description: Get population-based coverage data by district.

Path Parameter:

  • locId (required): Location ID

Response: List<Map<String, Object>>

28. Yearly Immunization Monitoring​

GET /immunization-monitoring-yearly

Description: Get yearly immunization monitoring data.

Query Parameters:

  • pId (optional): Program ID
  • locId (optional): Location ID
  • center (optional): Center
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (required): From date (dd-MM-yyyy)

Response: List

29. Monthly Population-Based Immunization​

GET /population-based-monthly-immunization

Description: Get monthly population-based immunization data.

Query Parameters:

  • Same as yearly immunization monitoring
  • type (required): Report type

Response: List

30. Monthly Population-Based TT Immunization​

GET /population-based-monthly-immunization-TT

Description: Get monthly population-based TT immunization data.

Query Parameters: Same as yearly immunization monitoring (except type)

Response: List

31. Defaulters Coverage by Vaccine​

GET /defaulters-coverage-by-vaccine

Description: Get defaulters coverage statistics by vaccine.

Query Parameters: Same as yearly enrollment summary

Response: List

32. Dropout Rate by Year​

GET /dropout-rate-by-year

Description: Get dropout rate statistics by year.

Query Parameters:

  • locId (optional): Location ID
  • year (optional): Year

Response: List

33. Defaulters Coverage by Vaccinator​

GET /defaulters-coverage-by-vaccinator

Description: Get defaulters coverage statistics by vaccinator.

Query Parameters: Same as yearly enrollment summary

Response: List

34. District Targets​

GET /get-district-targets

Description: Get district targets.

Query Parameters:

  • center (optional): Center
  • tdate (optional): Date (dd-MM-yyyy)

Response: List

35. Follow-up Age Appropriate Summary​

GET /summary-followup-age-appropriate

Description: Get follow-up age appropriate summary.

Query Parameters:

  • locId (optional): Location ID
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (optional): From date (dd-MM-yyyy)

Response: List

36. Live Entries for Vaccinators​

GET /live_entries

Description: Get live entries for vaccinators.

Query Parameters:

  • locId (optional): Location ID
  • date (required): Date (dd-MM-yyyy)
  • locationType (required): Location type

Response: List

37. Daily Summary​

GET /daily-summary

Description: Get daily vaccination summary.

Query Parameters:

  • locationId (required): Location ID
  • filterDatefrom (required): Date (dd-MM-yyyy)

Response: JSON String

38. Defaulters Children List​

GET /defaulters_list

Description: Get list of defaulters children.

Query Parameters:

  • API_KEY (optional): API key
  • locId (optional): Location ID
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (optional): From date (dd-MM-yyyy)
  • vaccinatorId (optional): Vaccinator ID
  • scheduledOnly (optional): Scheduled only flag
  • type (optional): Report type (PDF/JSON)

Response: List or PDF file

39. Monthly Summary Vaccinations​

GET /monthly-summary-vaccinations

Description: Get monthly vaccination summary.

Query Parameters:

  • locationId (required): Location ID
  • filterDatefrom (required): Date (dd-MM-yyyy)

Response: JSON String

40. Zero Dose Report​

GET /zero_dose

Description: Get zero dose report.

Query Parameters:

  • API_KEY (optional): API key
  • locId (optional): Location ID
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (optional): From date (dd-MM-yyyy)
  • type (optional): Report type (PDF/JSON)

Response: List or PDF file

41. Compliance Report​

GET /complianceReport

Description: Get compliance report.

Query Parameters:

  • locationId (optional): Location ID
  • filterDate (optional): Filter date (yyyy-MM or yyyy-MM-dd)
  • crumb (optional): Crumb parameter
  • type (optional): Report type (CSV/JSON)

Response: List<LinkedHashMap<String, Object>> or CSV file

42. Compliance Report V2​

GET /complianceReportv2

Description: Get compliance report (enhanced version).

Query Parameters: Same as complianceReport

Response: List<Map<String, Object>> or CSV file

43. Daily Register​

GET /dailyRegister

Description: Get daily vaccination registry.

Query Parameters:

  • API_KEY (optional): API key
  • locId (optional): Location ID
  • tdate (optional): Date (dd-MM-yyyy)
  • outOfArea (optional): Out of area flag
  • vaccinatorId (optional): Vaccinator ID
  • type (optional): Report type (PDF/JSON)

Response: List or PDF file

44. Compliance Coverage Graph​

GET /complianceCoverageGraph

Description: Get compliance coverage graph data.

Query Parameters:

  • location (required): Location
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)
  • locationType (required): Location type

Response: Map<String, Object>

45. Zero Dose Graph​

GET /zeroDoseGraph

Description: Get zero dose graph data.

Query Parameters:

  • location (required): Location
  • filterDatefrom (required): Date (dd-MM-yyyy)

Response: Map<String, Object>

46. Compliance Graph Monthly​

GET /complianceGraphMonthly

Description: Get monthly compliance graph data.

Query Parameters:

  • location (required): Location
  • filterDatefrom (required): Date (dd-MM-yyyy)

Response: Map<Integer, Object>

47. Compliance Graphs by Week​

GET /compliance-graphs-by-week

Description: Get weekly compliance graph data.

Query Parameters:

  • locationId (optional): Location ID
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)
  • locationType (optional): Location type

Response: List

48. Child Registry​

GET /childRegistry

Description: Get child registry records.

Query Parameters:

  • API_KEY (optional): API key
  • locId (optional): Location ID
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (optional): From date (dd-MM-yyyy)
  • type (optional): Report type (PDF/JSON)

Response: List or PDF file

49. Attendance Summary​

GET /attendanceSummary

Description: Get attendance summary.

Query Parameters:

  • locationId (optional): Location ID
  • filterDate (optional): Filter date (yyyy-MM or yyyy-MM-dd)
  • type (optional): Report type

Response: List<LinkedHashMap<String, Object>>

50. Attendance Summary V2​

GET /attendanceSummaryV2

Description: Get attendance summary (enhanced version).

Query Parameters: Same as attendanceSummary

Response: List<Map<String, Object>>

51. Attendance Deficient Vaccinators​

GET /attendanceDeficientVaccinator

Description: Get list of attendance deficient vaccinators.

Query Parameters: Same as attendanceSummary

Response: List<Map<String, Object>>

52. Stock Report​

GET /stockReport

Description: Get stock report.

Query Parameters:

  • locationId (optional): Location ID
  • filterDate (optional): Filter date (yyyy-MM or yyyy-MM-dd)
  • type (optional): Report type (CSV/JSON)

Response: List<LinkedHashMap<String, Object>> or CSV file

53. Attendance Breakdown​

GET /attendance_breakdown

Description: Get daily attendance breakdown.

Query Parameters:

  • locId (optional): Location ID
  • datefrom (optional): Start date (dd-MM-yyyy)
  • date (required): Date (dd-MM-yyyy)
  • range (optional): Range type (daywise)
  • locationType (required): Location type

Response: List

54. Women Defaulters List​

GET /women_defaulters_list

Description: Get women defaulters list.

Query Parameters:

  • API_KEY (optional): API key
  • locId (optional): Location ID
  • vaccinatorId (optional): Vaccinator ID
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (optional): From date (dd-MM-yyyy)
  • scheduledOnly (optional): Scheduled only flag
  • type (optional): Report type (PDF/JSON)

Response: List or PDF file

55. Women Identified List​

GET /women_identified_list

Description: Get women identified list.

Query Parameters: Same as women defaulters list

Response: List or PDF file

56. Facts Incentives​

GET /factsIncentives

Description: Get facts about incentives.

Query Parameters:

  • locationId (optional): Location ID
  • filterDatefrom (required): Start date (dd-MM-yyyy)
  • filterDateto (required): End date (dd-MM-yyyy)

Response: JSON String

57. Facts MCCT Stats​

GET /factsMcctStats

Description: Get facts about MCCT statistics.

Query Parameters: Same as facts incentives

Response: JSON String

58. Coverage Change MCCTS​

GET /coverage-change-mccts

Description: Get yearly immunization coverage for MCCTS.

Query Parameters:

  • locId (optional): Location ID
  • tdate (optional): To date (dd-MM-yyyy)
  • fdate (required): From date (dd-MM-yyyy)

Response: List

59. Flagged to Resolve MCCTS​

GET /flagged-to-resolve-mccts

Description: Get cases flagged for resolution in MCCTS.

Query Parameters: Same as coverage change MCCTS

Response: List

60. Timeliness Graph MCCTS​

GET /timeliness-graph-mccts

Description: Get timeliness graph data for MCCTS.

Query Parameters: Same as coverage change MCCTS

Response: List

Data Synchronization Endpoints (DataRestResource.java)​

61. Get Updated Data​

GET /api/reports/immunization/getUpdatedData

Description: Get updated/new entities data for synchronization.

Query Parameters:

  • locationId (required): Location ID
  • lastSyncedTime (required): Last synchronization timestamp
  • entityType (required): Entity type
  • dataOffset (required): Data offset
  • pageSize (optional, default=500): Page size

Response: JSON String

Example Response:

json

{
"status": "success",
"data": [...],
"nextOffset": "..."

}

DHIS2 Integration Endpoints (DHIS2ReportingController.java)​

62. Get DHIS2 Data​

GET **/api/reports/dhis2/data

Description: Get data formatted for DHIS2 integration/export.

Query Parameters:

  • date (required): Reporting date

  • limit (required): Number of records to return

  • offset (required): Pagination offset

  • Response: List<DHIS2DataDTO>

Example Request:

text

GET /api/reports/dhis2/data?date=2024-01-15&limit=100&offset=0

HPV Reporting Endpoints (HPVResources.java)​

63. Get All HPV Daily Counts​

GET **/api/hpv/daily-count

Description: Get all HPV daily vaccination counts.

Query Parameters: None

  • Response: List<HpvDailyCount>

64. Get HPV Daily Count by Date​

GET /api/hpv/daily-count/{id}

Description: Get HPV daily count for a specific date.

Path Parameter:

  • id (required): Date in ISO format (YYYY-MM-DD)

Response: HpvDailyCount or 404 if not found

Example Request:

text

GET /api/hpv/daily-count/2024-01-15

---​

65. Get HPV Dashboard Records​

GET /api/hpv/dashboard-list

Description: Get filtered HPV vaccination records for dashboard display with pagination.

Query Parameters:

  • dateFrom (optional): Start date filter (yyyy-MM-dd)

  • dateTo (optional): End date filter (yyyy-MM-dd)

  • limit (optional, default=10): Number of records per page

  • offset (optional): Pagination offset (used to calculate page number)

  • Response: List<HPVDashboardDTO>

Paging Logic:​

  • Page = offset / limit (if both provided)

  • Default page size = 10

  • Sorted by creation date ascending

Example Request:

text

GET /api/hpv/dashboard-list?dateFrom=2024-01-01&dateTo=2024-01-31&limit=20&offset=0

---​

Defaulters Management Endpoints (DefaultersResources.java)​

66. Get Defaulters Children List​

GET /api/defaulters/children

Description: Get list of children who are defaulters (missed vaccinations) with pagination and filtering.

Query Parameters:

  • ucInclusion (required): UC inclusion criteria (e.g., "inside", "outside")

  • status (required): Status filter (e.g., "SCHEDULED", "MISSED")

  • locId (required): Location ID

  • filterDateFrom (required): Start date for filtering

  • filterDateTo (required): End date for filtering

  • age (required): Age filter criteria

  • startRecord (required): Starting record number (0-based)

  • limit (required): Number of records to return

  • Response: DefaulterListChildDTO containing total count and data

Special Logic:

  • When limit = 100000000: Returns all records and uses result size as total count

  • Otherwise: Executes separate count query for total rows

Example Request:

text

GET /api/defaulters/children?ucInclusion=inside&status=SCHEDULED&locId=123&filterDateFrom=2024-01-01&filterDateTo=2024-01-31&age=12&startRecord=0&limit=50

Database Procedures Used​

The service calls various stored procedures in the database:

Main Procedures:​

  1. unfepi_dwh.SummaryEnrollmentYearly
  2. unfepi_dwh.SummaryGenderBased
  3. unfepi.FactsChildrenFICProcedure
  4. unfepi.FactsChildrenProcedure
  5. unfepi.FactsQueryProcedure
  6. unfepi_dwh.CoverageReport
  7. unfepi_dwh.SummaryEnrByCenterCohort
  8. unfepi_dwh.SummaryEnrByVaccinator
  9. unfepi_dwh.SummaryTTEnrByCenterCohort
  10. unfepi_dwh.SummaryTTEnrByVaccinatorCohort
  11. unfepi_dwh.SummaryFollowupAgeAppropriate
  12. unfepi_dwh.SummaryImmunizationByVaccinator
  13. unfepi_dwh.SummaryImmunizationByCenter
  14. unfepi_dwh.SummaryRefusalByVaccinator
  15. unfepi_dwh.SummaryRefusalByCenter
  16. unfepi_dwh.SummaryTTImmunizationByVaccinator
  17. unfepi_dwh.SummaryImmunizationVisitByVaccinator
  18. unfepi_dwh.SummaryImmunizationTTByCenter
  19. VaccinatorAttendanceDayWise
  20. unfepi_dwh.SummaryImmunizationByYear
  21. PopulationBasedCoverageVaccination
  22. PopulationBasedCoverageVaccinationTT
  23. unfepi_dwh.SummaryDefaultersCoveredByVaccine
  24. unfepi_dwh.DropoutRate
  25. unfepi_dwh.SummaryDefaultersCoveredByVaccinator
  26. GetAncestry
  27. LocationAttributeParentByCenterId
  28. unfepi.VaccinatorLiveEntriesByVaccinator
  29. unfepi.VaccinatorLiveEntriesByLocation
  30. unfepi_dwh.DefaulterListChild
  31. unfepi_dwh.DefaultersCoverageList
  32. ZeroDoseReport
  33. unfepi.DailyVaccinationRegistry
  34. unfepi_dwh.ComplianceGraphByLocation
  35. unfepi_dwh.ZeroDoseCoverageGraph
  36. unfepi_dwh.complianceGraphMonthly
  37. unfepi_dwh.ComplianceWeekWise
  38. unfepi.ZeroDoseFromChildRegistry
  39. unfepi.AttendanceSummary
  40. unfepi.stockReport
  41. unfepi_dwh.DefaulterListWomen
  42. unfepi_dwh.IdentifiedListWomen
  43. unfepi.SummaryCaseResolution
  44. unfepi_dwh.SummaryTimelinessByYear

🔧 Technical Details​

Dependencies:​

  • Framework: Spring Boot
  • Database: MySQL
  • Template Engine: JasperReports (for PDF generation)
  • JSON Libraries: org.codehaus.jettison
  • Date/Time: Joda Time

Key Components:​

  1. JdbcTemplate: Used for all database operations
  2. LocationRepository: Spring Data JPA repository for Location entity
  3. ReportsDownloadResource: Helper class for report downloads (PDF/CSV)
  4. DataQuery: Enum containing SQL queries
  5. ResponseBuilder: Utility for building JSON responses

Data Models Used:​

  • Location
  • Vaccinator
  • User
  • Organization
  • LeaveManagement
  • ComplianceManagement
  • VaccinationCenterCloseDay
  • PublicHoliday

Date Format:​

  • Input dates: dd-MM-yyyy
  • Database dates: yyyy-MM-dd
  • Month-only formats: yyyy-MM

Error Handling​

Common Error Responses:​

  1. Invalid Date Format: Returns empty result or default values
  2. Database Errors: Returns empty collections ([], {})
  3. Missing Parameters: May return null or empty results

Exception Handling:​

  • Most methods catch exceptions and return empty results
  • Stack traces are printed to console
  • PDF generation errors return error messages

Integration Notes​

Migration from Zindagi Mehfooz (ZM):​

  1. Data Source: Reads from replica database
  2. API Gateway: All reporting calls should be routed to this service
  3. Performance: Designed for heavy report generation
  4. Separation of Concerns: Separates reporting logic from main application

Caching Strategy:​

Consider implementing caching for:

  • Frequently accessed reports
  • Master data (locations, vaccinators)
  • Aggregated statistics

Security:​

  • API_KEY parameter used for some endpoints
  • Consider adding JWT authentication for production

Monitoring & Logging​

Key Metrics to Monitor:​

  1. Response times for each report type
  2. Database query performance
  3. Memory usage during PDF generation
  4. API error rates

Logging Recommendations:​

  1. Log all API calls with parameters
  2. Track report generation times
  3. Monitor database connection pool usage
  4. Log PDF/CSV generation statistics

Scalability Considerations​

Horizontal Scaling:​

  • Stateless service design
  • Database connection pooling
  • External session management if needed

Performance Optimization:​

  1. Database Indexing: Ensure proper indexes on report tables
  2. Query Optimization: Regular review of stored procedures
  3. Pagination: Implement for large datasets
  4. Async Processing: Consider for heavy reports

Deployment:​

  • Containerize with Docker
  • Use orchestration (Kubernetes)
  • Implement health checks
  • Set up auto-scaling rules